package org.terramagnet.mvcframework.resource;

import java.io.InputStream;
import java.util.Date;
import java.util.List;
import org.springframework.web.multipart.MultipartFile;
import org.terramagnet.mvcframework.tools.Paginal;

/**
 * 资源服务器.
 *
 * @author lip
 */
public interface ResourceService {

    /**
     * 创建资源. 创建后的资源是<strong>临时的</strong>。 <strong>临时的</strong>资源会在一段时间后删除。
     *
     * @param bucket 资源桶 资源桶用于对资源进行业务分组.
     * @param multipartFiles 资源文件
     * @return 资源key集合
     */
    List<String> create(String bucket, MultipartFile... multipartFiles);

    /**
     * 创建资源. 创建后的资源是<strong>临时的</strong>。 <strong>临时的</strong>资源会在一段时间后删除。
     *
     * @param bucket 资源桶 资源桶用于对资源进行业务分组.
     * @param filename 资源文件原名称
     * @param inputStream 资源输入流. <strong>不会关闭该流</strong>
     * @return 资源key
     */
    String create(String bucket, String filename, InputStream inputStream);

    /**
     * 删除资源.
     */
    void delete(String... keys);

    /**
     * 连接资源. 连接后的资源才是<strong>正式的</strong>.
     *
     * @param key 资源KEY
     * @param module 扩展参数——所属模块
     * @param principal 扩展参数——所属用户
     */
    void link(String key, String module, String principal);

    /**
     * 判断资源路径是否是绝对URL.
     */
    boolean isAbsoluteUrl(String path);

    /**
     * 查看资源内容.
     *
     * @param key 资源KEY 支持资源URL和资源ID,支持缩放图
     * @param thumbnail 是否返回缩略图资源. 外部资源会忽略该选项
     * @return 资源或{@code null}
     */
    ResourceArchive view(String key, boolean thumbnail);

    /**
     * 分页查询资源表. 查询条件为{@code null}表示忽略该条件。
     *
     * @param temporary 查询条件——是否临时资源
     * @param from 查询条件——资源的创建起始时间（包含）
     * @param to 查询条件——资源的创建结束时间（不包含）
     * @param page 分页参数——页码
     * @param size 分页参数——大小
     * @return 资源列表. 无记录时返回空列表.
     */
    Paginal<ResourceArchive> page(Boolean temporary, Date from, Date to, int page, int size);

}
